Amiga Tools 2

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Tools 2 / Amiga Tools 2.iso / tools / jade / man / jade.info-4 (.txt) < prev next >

Wrap

GNU Info File | 1995-03-09 | 50KB | 1,074 lines

This is Info file jade.info, produced by Makeinfo-1.55 from the input file jade.texi. START-INFO-DIR-ENTRY * Jade: (jade). An editor for X11 and AmigaDOS END-INFO-DIR-ENTRY This is Edition 1.3, last updated 7 October 1994, of `The Jade Manual', for Jade, Version 3.2. Jade is a text editor for X11 (on Unix) and the Amiga. Copyright 1993, 1994 John Harper. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. File: jade.info, Node: Characters, Prev: Numeric Predicates, Up: Numbers Characters ---------- In Jade characters are stored in integers. Their read syntax is a question mark followed by the character itself which may be an escape sequence introduced by a backslash. For details of the available escape sequences see *Note Strings::. ?a => 97 ?\n => 10 ?\177 => 127 - Function: alpha-char-p CHARACTER This function returns `t' when CHARACTER is one of the alphabetic characters. (alpha-char-p ?a) => t - Function: upper-case-p CHARACTER When CHARACTER is one of the upper-case characters this function returns `t'. - Function: lower-case-p CHARACTER Returns `t' when CHARACTER is lower-case. - Function: digit-char-p CHARACTER This function returns `t' when CHARACTER is one of the decimal digit characters. - Function: alphanumericp CHARACTER This function returns `t' when CHARACTER is either an alphabetic character or a decimal digit character. - Function: space-char-p CHARACTER Returns `t' when CHARACTER is a white-space character (space, tab, newline or form feed). - Function: char-upcase CHARACTER This function returns the upper-case equivalent of CHARACTER. If CHARACTER is already upper-case or has no upper-case equivalent it is returned unchanged. (char-upcase ?a) => 65 ;`A' (char-upcase ?A) => 65 ;`A' (char-upcase ?!) => 33 ;`!' - Function: char-downcase CHARACTER Returns the lower-case equivalent of the character CHARACTER. File: jade.info, Node: Sequences, Next: Symbols, Prev: Numbers, Up: Programming Jade Sequences ========= Sequences are ordered groups of objects, there are several primitive types which can be considered sequences, each with its own good and bad points. A sequence is either an array or a list, where an array is either a vector or a string. - Function: sequencep OBJECT This function returns `t' if OBJECT is a sequence, `nil' otherwise. * Menu: * Cons Cells:: An ordered pair of two objects * Lists:: Chains of cons cells * Vectors:: A chunk of memory holding a number of objects * Strings:: Strings are efficiently-stored vectors * Array Functions:: Accessing elements in vectors and strings * Sequence Functions:: These work on any type of sequence File: jade.info, Node: Cons Cells, Next: Lists, Up: Sequences Cons Cells ---------- A "cons cell" is an ordered pair of two objects, the "car" and the "cdr". The read syntax of a cons cell is an opening parenthesis followed by the read syntax of the car, a dot, the read syntax of the cdr and a closing parenthesis. For example a cons cell with a car of 10 and a cdr of the string `foo' would be written as, (10 . "foo") - Function: cons CAR CDR This function creates a new cons cell. It will have a car of CAR and a cdr of CDR. (cons 10 "foo") => (10 . "foo") - Function: consp OBJECT This function returns `t' if OBJECT is a cons cell and `nil' otherwise. (consp '(1 . 2)) => t (consp nil) => nil (consp (cons 1 2)) => t In Lisp an "atom" is any object which is not a cons cell (and is, therefore, atomic). - Function: atom OBJECT Returns `t' if OBJECT is an atom (not a cons cell). Given a cons cell there are a number of operations which can be performed on it. - Function: car CONS-CELL This function returns the object which the car of the cons cell CONS-CELL. (car (cons 1 2)) => 1 (car '(1 . 2)) => 1 - Function: cdr CONS-CELL This function returns the cdr of the cons cell CONS-CELL. (cdr (cons 1 2)) => 2 (cdr '(1 . 2)) => 2 - Function: rplaca CONS-CELL NEW-CAR This function sets the value of the car in the cons cell CONS-CELL to NEW-CAR. The value returned is NEW-CAR. (setq x (cons 1 2)) => (1 . 2) (rplaca x 3) => 3 x => (3 . 2) - Function: rplacd CONS-CELL NEW-CDR This function is similar to `rplacd' except that the cdr slot of CONS-CELL is modified. File: jade.info, Node: Lists, Next: Vectors, Prev: Cons Cells, Up: Sequences Lists ----- A list is a sequence of zero or more objects, the main difference between lists and vectors is that lists are more dynamic: they can change size, be split, reversed, concatenated, etc... very easily. In Lisp lists are not a primitive type; instead singly-linked lists are created by chaining cons cells together (*note Cons Cells::.). - Function: listp OBJECT This functions returns `t' when its argument, OBJECT, is a list (i.e. either a cons cell or `nil'). * Menu: * List Structure:: How lists are built from cons cells * Building Lists:: Dynamically creating lists * Accessing List Elements:: Getting at the elements which make the list * Modifying Lists:: How to alter the contents of a list * Association Lists:: Lists can represent relations * Infinite Lists:: Circular data structures in Lisp File: jade.info, Node: List Structure, Next: Building Lists, Up: Lists List Structure .............. Each element in a list is given its own cons cell and stored in the car of that cell. The list object is then constructed by making the cdr of a cell contain the cons cell of the next element (and hence the whole tail of the list). The cdr of the cell containing the last element in the list is `nil'. A list of zero elements is represented by the symbol `nil'. The read syntax of a list is an opening parenthesis, followed by the read syntax of zero or more space-separated objects, followed by a closing parenthesis. Alternatively, lists can be constructed `manually' using dotted-pair notation. All of the following examples result in the same list of five elements: the numbers from zero to four. (0 1 2 3 4) (0 . (1 . (2 . (3 . (4 . nil))))) (0 1 2 . (3 4)) An easy way to visualise lists and how they are constructed is to see each cons cell in the list as a separate "box" with pointers to its car and cdr, +-----+-----+ | o | o----> cdr +--|--+-----+ | --> car Complex box-diagrams can now be drawn to represent lists. For example the following diagram represents the list `(1 2 3 4)'. +-----+-----+ +-----+-----+ +-----+-----+ +-----+-----+ | o | o----> | o | o----> | o | o----> | o | o----> nil +--|--+-----+ +--|--+-----+ +--|--+-----+ +--|--+-----+ | | | | --> 1 --> 2 --> 3 --> 4 A more complex example, the list `((1 2) (foo bar))' can be drawn as, +-----+-----+ +-----+-----+ | o | o---------------------------> | o | o----> nil +--|--+-----+ +--|--+-----+ | | +-----+-----+ +-----+-----+ +-----+-----+ +-----+-----+ | o | o----> | o | o----> nil | o | o----> | o | o----> nil +--|--+-----+ +--|--+-----+ +--|--+-----+ +--|--+-----+ | | | | --> 1 --> 2 --> foo --> bar Sometimes when manipulating complex list structures it is very helpful to make a diagram of what it is that's being manipulated. File: jade.info, Node: Building Lists, Next: Accessing List Elements, Prev: List Structure, Up: Lists Building Lists .............. It has already been shown how you can create lists using the Lisp reader; this method does have a drawback though: the list created is effectively static. If you modify the contents of the list and that list was created when a function was defined the list will remain modified for all future invocations of that function. This is not usually a good idea, consider the following function definition, (defun bogus-function (x) "Return a list whose first element is nil and whose second element is X." (let ((result '(nil nil))) ;Static list which is filled in each time (rplaca (cdr result) x) ; the function is called result)) This function does in fact do what its documentation claims, but a problem arises when it is called more than once, (setq x (bogus-function 'foo)) => (nil foo) (setq y (bogus-function 'bar)) => (nil bar) ;The first result has been destroyed x => (nil bar) ;See! This example is totally contrived -- no one would ever write a function like the one in the example but it nicely demonstrates the need for a dynamic method of creating lists. - Function: list &rest ELEMENTS This function creates a list out of its arguments, if zero arguments are given the empty list, `nil', is returned. (list 1 2 3) => (1 2 3) (list (major-version-number) (minor-version-number)) => (3 2) (list) => nil ;Equivalent to `()' - Function: make-list LENGTH &optional INITIAL-VALUE This function creates a list LENGTH elements long. If the INITIAL-VALUE argument is given it defines the value of all elements in the list, if it is not given they are all `nil'. (make-list 2) => (nil nil) (make-list 3 t) => (t t t) (make-list 0) => nil - Function: append &rest LISTS This function creates a new list with the elements of each of its arguments (which must be lists). Unlike the function `nconc' this function preserves all of its arguments. (append '(1 2 3) '(4 5)) => (1 2 3 4 5) (append) => nil What actually happens is that all arguments but the last are copied then the last argument is linked on to the end of the list (uncopied). (setq foo '(1 2)) => (1 2) (setq bar '(3 4)) => (3 4) (setq baz (append foo bar)) => (1 2 3 4) (eq (nthcdr 2 baz) bar) => t The following diagram shows the final state of the three variables more clearly, foo--> +-----+-----+ +-----+-----+ | o | o----> | o | | +--|--+-----+ +--|--+-----+ | | o--> 1 o--> 2 bar | | -> baz--> +--|--+-----+ +--|--+-----+ +-----+-----+ +-----+-----+ | o | o----> | o | o----> | o | o----> | o | | +-----+-----+ +-----+-----+ +--|--+-----+ +--|--+-----+ | | --> 3 --> 4 Note how `foo' and the first half of `baz' use the *same* objects for their elements -- copying a list only copies its cons cells, its elements are reused. Also note how the variable `bar' actually references the mid-point of `baz' since the last list in an `append' call is not copied. - Function: reverse LIST This function returns a new list; it is made from the elements of the list LIST in reverse order. Note that this function does not alter its argument. (reverse '(1 2 3 4)) => (4 3 2 1) As a postscript to this section, the function used as an example at the beginning could now be written as, (defun not-so-bogus-function (x) (list nil x)) Also note that the `cons' function can be used to create lists by hand and to add new elements onto the front of a list. File: jade.info, Node: Accessing List Elements, Next: Modifying Lists, Prev: Building Lists, Up: Lists Accessing List Elements ....................... The most powerful method of accessing an element in a list is via a combination of the `car' and `cdr' functions. There are other functions which provide an easier way to get at the elements in a flat list. These will usually be faster than a string of `car' and `cdr' operations. - Function: nth COUNT LIST This function returns the element COUNT elements down the list, therefore to access the first element use a COUNT of zero (or even better the `car' function). If there are too few elements in the list and no element number COUNT can be found `nil' is returned. (nth 3 '(0 1 2 3 4 5)) => 3 (nth 0 '(foo bar) => foo - Function: nthcdr COUNT LIST This function takes the cdr of the list LIST COUNT times, returning the last cdr taken. (nthcdr 3 '(0 1 2 3 4 5)) => (3 4 5) (nthcdr 0 '(foo bar)) => (foo bar) - Function: last LIST This function returns the last element in the list LIST. If the list has zero elements `nil' is returned. (last '(1 2 3)) => 3 (last '()) => nil - Function: member OBJECT LIST This function scans through the list LIST until it finds an element which is `equal' to OBJECT. The tail of the list (the cons cell whose car is the matched object) is then returned. If no elements match OBJECT then the empty list `nil' is returned. (member 'c '(a b c d e)) => (c d e) (member 20 '(1 2)) => nil - Function: memq OBJECT LIST This function is similar to `member' except that comparisons are performed by the `eq' function not `equal'. File: jade.info, Node: Modifying Lists, Next: Association Lists, Prev: Accessing List Elements, Up: Lists Modifying Lists ............... The `nthcdr' function can be used in conjunction with the `rplaca' function to modify an arbitrary element in a list. For example, (rplaca (nthcdr 2 '(0 1 2 3 4 5)) 'foo) => foo sets the third element of the list `(0 1 2 3 4 5)' to the symbol called `foo'. There are also functions which modify the structure of a whole list. These are called "destructive" operations because they modify the actual structure of a list -- no copy is made. This can lead to unpleasant side effects if care is not taken. - Function: nconc &rest LISTS This function is the destructive equivalent of the function `append', it modifies its arguments so that it can return a list which is the concatenation of the elements in its arguments lists. Like all the destructive functions this means that the lists given as arguments are modified (specifically, the cdr of their last cons cell is made to point to the next list). This can be seen with the following example (similar to the example in the `append' documentation). (setq foo '(1 2)) => (1 2) (setq bar '(3 4)) => (3 4) (setq baz (nconc foo bar)) => (1 2 3 4) foo => (1 2 3 4) ;`foo' has been altered! (eq (nthcdr 2 baz) bar) => t The following diagram shows the final state of the three variables more clearly, foo--> bar--> baz--> +-----+-----+ +-----+-----+ +-----+-----+ +-----+-----+ | o | o----> | o | o----> | o | o----> | o | | +--|--+-----+ +--|--+-----+ +--|--+-----+ +--|--+-----+ | | | | --> 1 --> 2 --> 3 --> 4 - Function: nreverse LIST This function rearranges the cons cells constituting the list LIST so that the elements are in the reverse order to what they were. (setq foo '(1 2 3)) => (1 2 3) (nreverse foo) => (3 2 1) foo => (1) ;`foo' wasn't updated when the list ; was altered. - Function: delete OBJECT LIST This function destructively removes all elements of the list LIST which are `equal' to OBJECT then returns the modified list. (delete t '(nil t nil t nil)) => (nil nil nil) When this function is used to remove an element from a list which is stored in a variable that variable must be set to the return value of the `delete' function. Otherwise, if the first element of the list has to be deleted (because it is `equal' to OBJECT) the value of the variable will not change. (setq foo '(1 2 3)) => (1 2 3) (delete 1 foo) => (2 3) foo => (1 2 3) (setq foo (delete 1 foo)) => (2 3) - Function: delq OBJECT LIST This function is similar to the `delete' function, the only difference is that the `eq' function is used to compare OBJECT with each of the elements in LIST, instead of the `equal' function which is used by `delete'. File: jade.info, Node: Association Lists, Next: Infinite Lists, Prev: Modifying Lists, Up: Lists Association Lists ................. An "association list" (or "alist") is a list mapping key values to to other values. Each element of the alist is a cons cell, the car of which is the "key", the cdr is the value that it associates to. For example an alist could look like, ((fred . 20) (bill . 30)) this alist has two keys, `fred' and `bill' which both associate to an integer (20 and 30 respectively). It is possible to make the associated values lists, this looks like, ((fred 20 male) (bill 30 male) (sue 25 female)) in this alist the symbol `fred' is associated with the list `(20 male)'. There are a number of functions which let you interrogate an alist with a given key for its association. - Function: assoc KEY ALIST This function scans the association list ALIST for the first element whose car is `equal' to KEY, this element is then returned. If no match of KEY is found `nil' is returned. (assoc 'two '((one . 1) (two . 2) (three . 3))) => (two . 2) - Function: assq KEY ALIST Similar to the function `assoc' except that the function `eq' is used to compare elements instead of `equal'. It is not usually wise to use `assq' when the keys of the alist may not be symbols -- `eq' won't think two objects are equivalent unless they are the *same* object! (assq "foo" '(("bar" . 1) ("foo" . 2))) => nil (assoc "foo" '(("bar" . 1) ("foo" . 2))) => ("foo" . 2) - Function: rassoc ASSOCIATION ALIST This function searches through ALIST until it finds an element whose cdr is `equal' to ASSOCIATION, that element is then returned. `nil' will be returned if no elements match. (rassoc 2 '((one . 1) (two . 2) (three . 3))) => (two . 2) - Function: rassq ASSOCIATION ALIST This function is equivalent to `rassoc' except that it uses `eq' to make comparisons. File: jade.info, Node: Infinite Lists, Prev: Association Lists, Up: Lists Infinite Lists .............. Sometimes it is useful to be able to create `infinite' lists -- that is, lists which appear to have no last element -- this can easily be done in Lisp by linking the cdr of the last cons cell in the list structure back to the beginning of the list. ----------------------------------- | | --> +-----+-----+ +-----+-----+ | | o | o----> | o | o----- +--|--+-----+ +--|--+-----+ | | --> 1 --> 2 The diagram above represents the infinite list `(1 2 1 2 1 2 ...)'. Infinite lists have a major drawback though, many of the standard list manipulation functions can not be used on them. These functions work by moving through the list until they reach the end. If the list has *no* end the function may never terminate and the only option is to send Jade an interrupt signal (*note Interrupting Jade::.). The only functions which may be used on circular lists are: the cons cell primitives (`cons', `car', `cdr', `rplaca', `rplacd'), `nth' and `nthcdr'. Also note that infinite lists can't be printed. File: jade.info, Node: Vectors, Next: Strings, Prev: Lists, Up: Sequences Vectors ------- A vector is a fixed-size sequence of Lisp objects, each element may be accessed in constant time -- unlike lists where the time taken to access an element is proportional to the position of the element. The read syntax of a vector is an opening square bracket, followed by zero or more space-separated objects, followed by a closing square bracket. For example, [zero one two three] In general it is best to use vectors when the number of elements to be stored is known and lists when the sequence must be more dynamic. - Function: vectorp OBJECT This function returns `t' if its argument, OBJECT, is a vector. - Function: vector &rest ELEMENTS This function creates a new vector containing the arguments given to the function. (vector 1 2 3) => [1 2 3] (vector) => [] - Function: make-vector SIZE &optional INITIAL-VALUE Returns a new vector, SIZE elements big. If INITIAL-VALUE is defined each element of the new vector is set to INITIAL-VALUE, otherwise they are all `nil'. (make-vector 4) => [nil nil nil nil] (make-vector 2 t) => [t t] File: jade.info, Node: Strings, Next: Array Functions, Prev: Vectors, Up: Sequences Strings ------- A string is a vector of characters (*note Characters::.), they are generally used for storing and manipulating pieces of text. Jade puts no restrictions on the values which may be stored in a string -- specifically, the null character (`^@') may be stored with no problems. The read syntax of a string is a double quote character, followed by the contents of the string, the object is terminated by a second double quote character. For example, `"abc"' is the read syntax of the string `abc'. Any backslash characters in the string's read syntax introduce an escape sequence; one or more of the following characters are treated specially to produce the next *actual* character in the string. The following escape sequences are supported (all are shown without their leading backslash `\' character). A newline character. A carriage return character. A form feed character. A TAB character. A `bell' character (this is Ctrl-g). The `control' code of the character C. This is calculated by toggling the seventh bit of the *upper-case* version of C. For example, \^C ;A Ctrl-c character (ASCII value 3) \^@ ;The NUL character (ASCII value 0) `012' The character whose ASCII value is the octal value `012'. After the backslash character the Lisp reader reads up to three octal digits and combines them into one character. `x12' The character whose ASCII value is the hexadecimal value `12', i.e. an `x' character followed by one or two hex digits. - Function: stringp OBJECT This function returns `t' if its argument is a string. - Function: make-string LENGTH &optional INITIAL-CHARACTER Creates a new string containing LENGTH characters, each character is initialised to INITIAL-CHARACTER (or to spaces if INITIAL-CHARACTER is not defined). (make-string 3) => " " (make-string 2 ?$) => "$$" - Function: concat &rest ARGS This function concatenates all of its arguments, ARGS, into a single string which is returned. If no arguments are given then the null string (`') results. Each of the ARGS may be a string, a character or a list or vector of characters. Characters are stored in strings modulo 256. (concat "foo" "bar") => "foobar" (concat "a" ?b) => "ab" (concat "foo" [?b ?a ?r]) => "foobar" (concat) => "" - Function: substring STRING START &optional END This function creates a new string which is a partial copy of the string STRING. The first character copied is START characters from the beginning of the string. If the END argument is defined it is the index of the character to stop copying at, if it is not defined all characters until the end of the string are copied. (substring "xxyfoozwx" 3 6) => "foo" (substring "xyzfoobar" 3) => "foobar" - Function: string= STRING1 STRING2 This function compares the two strings STRING1 and STRING2 -- if they are made from the same characters in the same order then `t' is returned, else `nil'. (string= "one" "one") => t (string= "one" "two") => nil Note that an alternate way to compare strings (or anything!) is to use the `equal' function. - Function: string< STRING1 STRING2 This function returns `t' if STRING1 is `less' than `string2'. This is determined by comparing the two strings a character at a time, the first pair of characters which do not match each other are then compared with a normal `less-than' function. In Jade the standard `<' function understands strings so `string<' is just a macro calling that function. (string< "abc" "abd") => t (string< "abc" "abb") => nil Functions are also available which match regular expressions with strings (*note Search and Match Functions::.) and which apply a mapping to each character in a string (*note Translation Functions::.). File: jade.info, Node: Array Functions, Next: Sequence Functions, Prev: Strings, Up: Sequences Array Functions --------------- - Function: arrayp OBJECT This function returns `t' if OBJECT is an array. - Function: aref ARRAY POSITION Returns the element of the array (vector or string) ARRAY POSITION elements from the first element (i.e. the first element is numbered zero). If no element exists at POSITION in ARRAY, `nil' is returned. (aref [0 1 2 3] 2) => 2 (aref "abcdef" 3) => 100 ;`d' - Function: aset ARRAY POSITION VALUE This function sets the element of the array ARRAY with an index of POSITION (counting from zero) to VALUE. An error is signalled if element POSITION does not exist. The result of the function is VALUE. (setq x [0 1 2 3]) => [0 1 2 3] (aset x 2 'foo) => foo x => [0 1 foo 3] File: jade.info, Node: Sequence Functions, Prev: Array Functions, Up: Sequences Sequence Functions ------------------ - Function: length SEQUENCE This function returns the length (an integer) of the sequence SEQUENCE. (length "abc") => 3 (length '(1 2 3 4)) => 4 (length [x y]) => 2 - Function: copy-sequence SEQUENCE Returns a new copy of the sequence SEQUENCE. Where possible (in lists and vectors) only the `structure' of the sequence is newly allocated: the same objects are used for the elements in both sequences. (copy-sequence "xy") => "xy" (setq x '("one" "two")) => ("one" "two") (setq y (copy-sequence x)) => ("one" "two") (eq x y) => nil (eq (car x) (car y)) => t - Function: elt SEQUENCE POSITION This function returns the element of SEQUENCE POSITION elements from the beginning of the sequence. This function is a combination of the `nth' and `aref' functions. (elt [0 1 2 3] 1) => 1 (elt '(foo bar) 0) => foo File: jade.info, Node: Symbols, Next: Evaluation, Prev: Sequences, Up: Programming Jade Symbols ======= Symbols are objects with a name (usually a unique name), they are one of the most important data structures in Lisp since they are used to provided named variables (*note Variables::.) and functions (*note Functions::.). - Function: symbolp OBJECT This function returns `t' when its argument is a symbol. * Menu: * Symbol Syntax:: The read syntax of symbols * Symbol Attributes:: The objects stored in a symbol * Obarrays:: Vectors used to store symbols * Creating Symbols:: Allocating new symbols * Interning:: Putting a symbol into an obarray * Property Lists:: Each symbol has a set of properties File: jade.info, Node: Symbol Syntax, Next: Symbol Attributes, Up: Symbols Symbol Syntax ------------- The read syntax of a symbol is simply its name; if the name contains any meta-characters (whitespace or any from `()[]'";|') they will have to be entered specially. There are two ways to tell the reader that a meta-character is actually part of the symbol's name: 1. Precede the meta-character by a backslash character (`\'), for example: xy$z$ ;the symbol whose name is `xy(z)' 2. Enclose part of the name in vertical lines (two `|' characters). All characters after the starting vertical line are copied as-is until the closing vertical line is encountered. For example: xy|(z)| ;the symbol `xy(z)' Here are some example read syntaxes. setq ; `setq' |setq| ; `setq' \s\e\t\q ; `setq' 1 ; the *number* 1 \1 ; the *symbol* `1' |!$%zf78&| ; `!$%zf78&' foo|(bar)| ; `foo(bar)' foo$bar$ ; `foo(bar)' File: jade.info, Node: Symbol Attributes, Next: Obarrays, Prev: Symbol Syntax, Up: Symbols Symbol Attributes ----------------- All symbols have four basic attributes, most important is the "print name" of the symbol. This is a string containing the name of the symbol, after it has been defined (when the symbol is first created) it may not be changed. - Function: symbol-name SYMBOL This function returns the print name of the symbol SYMBOL. (symbol-name 'unwind-protect) => "unwind-protect" Each symbol also has a "value" cell storing the value of this symbol when it is referenced as a variable. Usually this cell is accessed implicitly by evaluating a variable form but it can also be read via the `symbol-value' function(1) (*note Variables::.). Similar to the value cell each symbol also has a "function" cell which contains the function definition of the symbol (*note Named Functions::.). The `symbol-function' function can be used to read this cell and the `fset' function to set it. Lastly, there is the symbol's "property list", this is similar to an alist (*note Association Lists::.) and provides a method of storing arbitrary extra values in each symbol. *Note Property Lists::. ---------- Footnotes ---------- (1) Actually buffer-local variables complicate matters but you'll learn about that later. File: jade.info, Node: Obarrays, Next: Creating Symbols, Prev: Symbol Attributes, Up: Symbols Obarrays -------- An "obarray" is the structure used to ensure that no two symbols have the same name and to provide quick access to a symbol given its name. An obarray is basically a vector (with a slight wrinkle), each element of the vector is a chain of symbols which share the same hash-value (a "bucket"). These symbols are chained together through links which are invisible to Lisp programs: if you examine an obarray you will see that each bucket looks as though it has at most one symbol stored in it. The normal way to reference a symbol is simply to type its name in the program, when the Lisp reader encounters a name of a symbol it looks in the default obarray for a symbol of that name. If the named symbol doesn't exist it is created and hashed into the obarray -- this process is known as "interning" the symbol, for more details see *Note Interning::. - Variable: obarray This variable contains the obarray that the `read' function uses when interning symbols. If you change this I hope you know what you're doing. - Function: make-obarray SIZE This function creates a new obarray with SIZE hash buckets (this should be a prime number for best results). This is the only correct way of making an obarray. - Function: find-symbol SYMBOL-NAME &optional OBARRAY This function scans the specified obarray (OBARRAY or the value of the variable `obarray' if OBARRAY is undefined) for a symbol whose name is the string SYMBOL-NAME. The value returned is the symbol if it can be found or `nil' otherwise. (find-symbol "setq") => setq - Function: apropos REGEXP &optional PREDICATE OBARRAY Returns a list of symbols from the obarray OBARRAY (or the default) whose print name matches the regular expression REGEXP. If PREDICATE is defined and not `nil', each symbol which matches REGEXP is applied to the function PREDICATE, if the value is `t' it is considered a match. The PREDICATE argument is useful for restricting matches to a certain type of symbol, for example only commands. (apropos "^yank" 'commandp) => (yank-rectangle yank yank-to-mouse) File: jade.info, Node: Creating Symbols, Next: Interning, Prev: Obarrays, Up: Symbols Creating Symbols ---------------- It is possible to allocate symbols dynamically, this is normally only necessary when the symbol is to be interned in the non-default obarray or the symbol is a temporary object which should not be interned (for example: labels in a compiler?). - Function: make-symbol PRINT-NAME This function creates and returns a new, uninterned, symbol whose print name is the string PRINT-NAME. Its variable and function value cells are void and it will have an empty property list. (make-symbol "foo") => foo - Function: gensym This function returns a new, uninterned, symbol which has a unique print name. (gensym) => G0001 (gensym) => G0002 File: jade.info, Node: Interning, Next: Property Lists, Prev: Creating Symbols, Up: Symbols Interning --------- "Interning" a symbol means to store it in an obarray so that it can be found in the future: all variables and named-functions are stored in interned symbols. When a symbol is interned a hash function is applied to its print name to determine which bucket in the obarray it should be stored in. Then it is simply pushed onto the front of that bucket's chain of symbols. Normally all interning is done automatically by the Lisp reader. When it encounters the name of a symbol which it can't find in the default obarray (the value of the variable `obarray') it creates a new symbol of that name and interns it. This means that no two symbols can have the same print name, and that the read syntax of a particular symbol always produces the same object (unless the value of `obarray' is altered). (eq 'some-symbol 'some-symbol) => t - Function: intern SYMBOL-NAME &optional OBARRAY This function uses `find-symbol' to search the OBARRAY (or the standard obarray) for a symbol called SYMBOL-NAME. If a symbol of that name is found it is returned, otherwise a new symbol of that name is created, interned into the obarray, and returned. (intern "setq") => setq (intern "my-symbol" my-obarray) => my-symbol - Function: intern-symbol SYMBOL &optional OBARRAY Interns the symbol SYMBOL into the obarray OBARRAY (or the standard one) then returns the symbol. If SYMBOL is currently interned in an obarray an error is signalled. (intern-symbol (make-symbol "foo")) => foo (intern-symbol 'foo) error--> Error: Symbol is already interned, foo - Function: unintern SYMBOL &optional OBARRAY This function removes the symbol SYMBOL from the obarray OBARRAY then returns the symbol. Beware! this function must be used with *extreme* caution -- once you unintern a symbol there's no way to recover it. (unintern 'setq) ;This is extremely stupid => setq File: jade.info, Node: Property Lists, Prev: Interning, Up: Symbols Property Lists -------------- Each symbol has a property list (or "plist"), this is a structure which associates an arbitrary Lisp object with a key (usually a symbol). The keys in a plist may not have any duplications (so that each property is only defined once). The concept of a property list is very similar to an association list (*note Association Lists::.) but there are two main differences: 1. Structure; each element of an alist represents one key/association pair. In a plist each pair of elements represents an association: the first is the key, the second the property. For example, where an alist may be, ((one . 1) (two . 2) (three . 3)) a property list would be, (one 1 two 2 three 3) 2. Plists have their own set of functions to modify the list. This is done destructively, altering the property list (since the plist is stored in only one location, the symbol, this is quite safe). - Function: get SYMBOL PROPERTY This function searches the property list of the symbol SYMBOL for a property `eq' to PROPERTY. If such a property is found it is returned, else the value `nil' is returned. (get 'if 'lisp-indent) => 2 (get 'set 'lisp-indent) => nil - Function: put SYMBOL PROPERTY NEW-VALUE `put' sets the value of the property PROPERTY to NEW-VALUE in the property list of the symbol SYMBOL. If there is an existing value for this property it is overwritten. The value returned is NEW-VALUE. (put 'foo 'prop 200) => 200 - Function: symbol-plist SYMBOL Returns the property list of the symbol SYMBOL. (symbol-plist 'if) => (lisp-indent 2) - Function: setplist SYMBOL PLIST This function sets the property list of the symbol SYMBOL to PLIST. (setplist 'foo '(zombie yes)) => (zombie yes) File: jade.info, Node: Evaluation, Next: Control Structures, Prev: Symbols, Up: Programming Jade Evaluation ========== So far I have only discussed a few of the various data types available and how the Lisp reader can convert textual descriptions of these types into Lisp objects. Obviously there has to be a way of actually computing something -- it would be difficult to write a useful program otherwise. What sets Lisp apart from other languages is that in Lisp there is no difference between programs and data: a Lisp program is just a sequence of Lisp objects which will be interpreted when the program is run. The subsystem which does this interpreting is called the "Lisp evaluator" and each expression to be evaluated is called a "form". The evaluator (the function `eval') examines the structure of the form that is applied to and computes the value of the form within the current environment. A form can be any type of data object; the only types which the evaluator treats specially are symbols (which stand for variables) and lists, anything else is returned as-is (and is called a "self-evaluating form"). - Function: eval FORM This function computes the value of the form which is its argument, within the current environment. The computed value is then returned. `eval' is the basic function for interpreting Lisp objects. * Menu: * Symbol Forms:: How variables are accessed * List Forms:: Subroutine calls * Self-Evaluating Forms:: Forms which don't get evaluated * Quoting:: How to prevent evaluation of forms File: jade.info, Node: Symbol Forms, Next: List Forms, Up: Evaluation Symbol Forms ------------ When the evaluator is applied to a symbol the computed value of the form is the object stored in the symbol's variable slot. Basically this means that to get the value of a variable you simply write its name. For example, buffer-list => (#<buffer *jade*> #<buffer programmer.texi>) this extract from a Lisp session shows the read syntax of a form to get the value of the variable `buffer-list' and the result when this form is evaluated. Since forms are evaluated within the current environment the value of a variable is its newest binding, or in the case of buffer-local variables, its value in the current buffer. *Note Variables::. If the value of an evaluated symbol is void an error is signalled. File: jade.info, Node: List Forms, Next: Self-Evaluating Forms, Prev: Symbol Forms, Up: Evaluation List Forms ---------- Forms which are lists are used to call a subroutine. The first element of the list is the subroutine which is to be called; all further elements are arguments to be applied to the subroutine. There are several different types of subroutines available: functions, macros, special forms and autoloads. When the evaluator finds a form which is a list it tries to classify the form into one of these four types. First of all it looks at the first element of the list, if it is a symbol it gets the value from the function slot of the symbol (note that the first element of a list form is *never* evaluated itself). This value (either the first element or the symbol's function value) is enough to classify the form into one of the four types. * Menu: * Function Call Forms:: `Normal' subroutines * Macro Call Forms:: Source code expansions * Special Forms:: Abnormal control structures * Autoload Forms:: Loading subroutines from files on the fly File: jade.info, Node: Function Call Forms, Next: Macro Call Forms, Up: List Forms Function Call Forms ................... The first element of a function call form is the name of the function, this can be either a symbol (in which case the symbol's function value is indirected through to get the real function definition) or a lambda expression (*note Lambda Expressions::.). Any other elements of the list are forms to be evaluated (in left to right order) and their values become the arguments to the function. The function is applied to these arguments and the result that it returns becomes the value of the form. For example, consider the form `(/ 100 (1+ 4))'. This is a function call to the function `/'. First the `100' form is evaluated: it returns the value `100', next the form `(1+ 4)' is evaluated. This is also a function call and computes to a value of `5' which becomes the second argument to the `/' function. Now the `/' function is applied to its arguments of `100' and `5' and it returns the value `20' which then becomes the value of the form `(/ 100 (1+ 4))'. (/ 100 (1+ 4)) == (/ 100 5) => 20 Or another example, (+ (- 10 (1- 7)) (* (1+ 2) 4) == (+ (- 10 6) (* (1+ 2) 4) == (+ 4 (* (1+ 2) 4) == (+ 4 (* 3 4)) == (+ 4 12) => 16 File: jade.info, Node: Macro Call Forms, Next: Special Forms, Prev: Function Call Forms, Up: List Forms Macro Call Forms ................ Macros are source code expansions, the general idea is that a macro is a function which using the unevaluated arguments applied to it, computes another form (the expansion of the macro and its arguments) which is then evaluated to provide the value of the form. For more details see *Note Macros::. File: jade.info, Node: Special Forms, Next: Autoload Forms, Prev: Macro Call Forms, Up: List Forms Special Forms ............. Special forms are built-in functions which the evaluator knows must be handled specially. The main difference between a special form and a function is that the arguments applied to a special form are *not* automatically evaluated -- if necessary the special form will evaluate arguments itself. This will be noted in the documentation of the special form. Special forms are generally used to provide control structures, for example, all of the conditional constructs are special forms (if all of their arguments, including the forms to be conditionally evaluated, were evaluated automatically this would defeat the object of being conditional!). The special forms supported by Jade are: `and', `catch', `cond', `defconst', `defmacro', `defun', `defvar', `error-protect', `function', `if', `let', `let*', `or', `prog1', `prog2', `progn', `quote', `setq', `setq-default', `unless', `unwind-protect', `when', `while', `with-buffer', `with-window'. File: jade.info, Node: Autoload Forms, Prev: Special Forms, Up: List Forms Autoload Forms .............. Not all modules of Jade are needed at once, autoload forms provide a means of marking that a function (or macro) is contained by a specific file of Lisp code. The first time that the function is accessed the autoload form will be evaluated; this loads the file that the function is contained by then re-evaluates the list form. By then the autoload form will have been overwritten in the symbol's function slot by the true function (when it was loaded) so the form will execute properly. An autoload form is a list whose first element is the symbol `autoload', for full details see *Note Autoloading::. File: jade.info, Node: Self-Evaluating Forms, Next: Quoting, Prev: List Forms, Up: Evaluation Self-Evaluating Forms --------------------- The computed value of any form which is not a symbol or a list will simply be the form itself and the form is said to be a "self-evaluating form". Usually the only forms to be evaluated in this way will be numbers, strings and vectors (since they are the only other data types which have read syntaxes) but the effect is the same for other types of data. This means that forms you know are self-evaluating do not have to be quoted to be used as constants (like lists and symbols do). "foo" => "foo" (eval (current-buffer)) => #<buffer programmer.texi> File: jade.info, Node: Quoting, Prev: Self-Evaluating Forms, Up: Evaluation Quoting ------- As the above sections explain some types of Lisp object have special meaning to the Lisp evaluator (namely the symbol and list types) this means that if you want to refer to a symbol or a list in a program you can't (yet) because the evaluator will treat the form as either a variable reference or a function call respectively. To get around this Lisp uses something called "quoting", the `quote' special form simply returns its argument, without evaluating it. For example, (quote my-symbol) => my-symbol the `quote' form prevents the `my-symbol' being treated as a variable -- it is effectively `hidden' from the evaluator. Writing `quote' all the time would be a bit boring so there is a shortcut: the Lisp reader treats any form X preceded by a single quote character (`'') as the form `(quote X)'. So the example above would normally be written as, 'my-symbol => my-symbol - Special Form: quote FORM This special form returns its single argument without evaluating it. This is used to "quote" constant objects to prevent them from being evaluated.